home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / langs / iconv8_e.arc / DOCS.ARC / IPD136.DOC < prev    next >
Encoding:
Text File  |  1985-11-20  |  18.2 KB  |  661 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                Version 8 of Icon for the Atari ST
  8.  
  9.                         Ralph E. Griswold
  10.     Department of Computer Science, The University of Arizona
  11.  
  12.  
  13.  
  14. 1.__Introduction
  15.  
  16.    Icon for the Atari ST is designed to run on both the 520 and
  17. 1040 models, but the limited amount of memory on the 520 makes
  18. its use there problematical for Version 8, which is larger than
  19. previous versions.  Icon for the the Atari ST is designed to run
  20. under a command-line processor, such as ASH.  This document
  21. assumes the use of ASH, although other command-line processors
  22. can be used.
  23.  
  24.    Version 8 of Icon for the Atari ST is distributed on a
  25. single-sided diskette, which includes executable binary files,
  26. ASH, a few test programs, and documentation in machine-readable
  27. form. Printed documentation is included with diskettes distri-
  28. buted by the Icon Project at the University of Arizona.
  29.  
  30.    This implementation of Icon is in the public domain and may be
  31. copied and used without restriction.  The Icon Project makes no
  32. warranties of any kind as to the correctness of this material or
  33. its suitability for any application.  The responsibility for the
  34. use of Icon lies entirely with the user.
  35.  
  36.  
  37. 2.__Documentation
  38.  
  39.    The basic reference for the Icon programming language is the
  40. book
  41.  
  42.      The Icon Programming Language, second edition, Ralph E.
  43.      Griswold and Madge T. Griswold, Prentice-Hall, Inc., Engle-
  44.      wood Cliffs, New Jersey, 1990. 365 pages. ISBN 0-13-447889-
  45.      4. $29.95.
  46.  
  47. This book is available from the Icon Project at the University of
  48. Arizona. It also can be ordered through any bookstore that han-
  49. dles special orders or by telephone directly from Prentice-Hall:
  50. (201) 767-9520.
  51.  
  52.    Note that the first edition of this book, published in 1983,
  53. describes an older version of Icon and does not contain informa-
  54. tion about many of the features of Version 8.
  55.  
  56.    A brief overview of Icon is contained in technical report TR
  57. 90-6 [1] (tr90-6.doc on the distribution diskette). Features that
  58. have been added to Icon since the book was written are described
  59. in TR 90-1 [2] (tr90-1.doc on the distribution diskette).  These
  60. technical reports, together with this document (ipd136.doc on
  61.  
  62.  
  63.  
  64. IPD136                        - 1 -                 April 2, 1990
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. this diskette), provide enough information to write and run sim-
  74. ple Icon programs, but persons who intend to use Icon extensively
  75. will need the book.
  76.  
  77.  
  78. 3.__Installing_Icon_on_the_Atari_ST
  79.  
  80.    Two executable binary files are needed to run Icon:
  81.  
  82.         icont.prg   translator and linker
  83.         iconx.prg   executor
  84.  
  85. These files should be located at a place on the PATH specifica-
  86. tion for your command-line processor.  Because of the way path
  87. searching is done, it is advisable to place these files in the
  88. root directory of one of your devices.
  89.  
  90.    Most of the distribution files are packaged in ARC format. A
  91. copy of ARC is included on the distribution diskette. The distri-
  92. bution files are:
  93.  
  94.         arc.prg      archiving utility
  95.         icon.arc     Icon executable binaries [214KB]
  96.         samples.arc  Icon programs and data [2KB]
  97.         docs.arc     documents [139KB]
  98.         readme       installation overview and recent notes
  99.         ash.prg      ASH
  100.         ash.hlp      ASH help file
  101.         ash.ini      ASH initialization file
  102.  
  103. The figures in brackets give the approximate amount of disk space
  104. needed when the files are extracted from their archives.
  105.  
  106.    First copy arc.prg to a place on your path.  To install the
  107. .prg files, set your current directory to the desired place and
  108. dearchive the files using arc on the distribution diskette*. For
  109. example, if the distribution diskette is in drive a:, the follow-
  110. ing will do:
  111.  
  112.         arc x a:icon.arc
  113.  
  114. The same technique can be used for extracting the remaining
  115. archived files.
  116.  
  117.  
  118.  
  119.  
  120. __________________________
  121. *If you are not familiar with the capabilities of  arc,  you
  122. can get a brief summary by
  123.  
  124.         arc h
  125.  
  126.  
  127.  
  128.  
  129.  
  130. IPD136                        - 2 -                 April 2, 1990
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 4.__Running_Icon_on_the_Atari_ST_-_Basic_Information
  140.  
  141.    Files containing Icon programs must have the extension .icn.
  142. Such files should be plain text files (without line numbers or
  143. other extraneous information).  The command processor icont runs
  144. icont and ilink to produce an ``icode'' file that can be executed
  145. by iconx.  For example, an Icon program in the file prog.icn is
  146. translated and linked by
  147.  
  148.         icont prog.icn
  149.  
  150. The result is an icode file with the name prog.icx.  This file
  151. can be run by
  152.  
  153.         iconx prog.icx
  154.  
  155.  
  156.    The extensions .icn and .icx are optional. For example, it is
  157. sufficient to use
  158.  
  159.         icont prog
  160.  
  161. and
  162.  
  163.         iconx prog
  164.  
  165.  
  166.    If input or output is redirected, i/o redirection must appear
  167. at the beginning of the arguments for iconx, as in
  168.  
  169.         iconx <prog.dat prog
  170.  
  171.  
  172.  
  173. 5.__Testing_the_Installation
  174.  
  175.    There are a few programs on the distribution diskette that can
  176. be used for testing the installation and getting a feel for run-
  177. ning Icon:
  178.  
  179.      hello.icn   This program prints the Icon version number,
  180.                  time, and date. Run this test as
  181.  
  182.                          icont hello
  183.                          iconx hello
  184.  
  185.  
  186.      cross.icn   This program prints all the ways that two words
  187.                  intersect in a common character. The file
  188.                  cross.dat contains typical data. Run this test
  189.                  as
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196. IPD136                        - 3 -                 April 2, 1990
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                          icont cross
  206.                          iconx <cross.dat cross
  207.  
  208.  
  209.      meander.icn This program prints the ``meandering strings''
  210.                  that contain all subsequences of a specified
  211.                  length from a given set of characters. Run this
  212.                  test as
  213.  
  214.                          icont meander
  215.                          iconx <meander.dat meander
  216.  
  217.  
  218.      roman.icn   This program converts Arabic numerals to Roman
  219.                  numerals. Run this test as
  220.  
  221.                          icont roman
  222.                          iconx roman
  223.  
  224.                  and provide some Arabic numbers from your con-
  225.                  sole.
  226.  
  227. If these tests work, your installation is probably correct and
  228. you should have a running version of Icon.
  229.  
  230.  
  231. 6.__More_on_Running_Icon
  232.  
  233.    For simple applications, the instructions for running Icon
  234. given in Section 4 may be adequate. The icont command processor
  235. supports a variety of options that may be useful in special
  236. situations.  There also are several aspects of execution that can
  237. be controlled with environment variables.  These are listed here.
  238. If you are new to Icon, you may wish to skip this section on the
  239. first reading but come back to it if you find the need for more
  240. control over the translation and execution of Icon programs.
  241.  
  242. 6.1__Arguments
  243.  
  244.    Arguments can be passed to the Icon program by appending them
  245. to the command line.  Such arguments are passed to the main pro-
  246. cedure as a list of strings.  For example,
  247.  
  248.         iconx prog text.dat log.dat
  249.  
  250. runs the icode file prog.icx, passing its main procedure a list
  251. of two strings, "text.dat" and "log.dat".  These arguments might
  252. be the names of files that prog.icn reads from and writes to. For
  253. example, the main procedure might begin as follows:
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. IPD136                        - 4 -                 April 2, 1990
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.         procedure main(a)
  272.            in := open(a[1]) | stop("cannot open input file")
  273.            out := open(a[2],"w") | stop("cannot open output file")
  274.                        .
  275.                        .
  276.                        .
  277.  
  278.  
  279. 6.2__The_Command_Processor
  280.  
  281.    The command processor icont can accept several Icon source
  282. files at one time.  When several files are given, they are
  283. translated and combined into a single icode file whose name is
  284. derived from the name of the first file.  For example,
  285.  
  286.         icont prog1 prog2
  287.  
  288. translates and links the files prog1.icn and prog2.icn and pro-
  289. duces one icode file, prog1.icx.
  290.  
  291.    If the -c option is given to icont, only translation is per-
  292. formed and intermediate ``ucode'' files with the extensions .u1
  293. and .u2 are kept.  For example,
  294.  
  295.         icont -c prog1
  296.  
  297. leaves prog1.u1 and prog1.u2, instead of linking them to produce
  298. prog1.icx. (The ucode files are deleted unless the -c option is
  299. used.) These ucode files can be used in a subsequent icont com-
  300. mand by using the .u1 name. This avoids having to translate the
  301. .icn file again. For example,
  302.  
  303.         icont prog2 prog1.u1
  304.  
  305. translates prog2.icn and links the result with the ucode files
  306. from a previous translation of prog1.icn. Note that only the .u1
  307. name is given. The extension can be abbreviated to .u, as in
  308.  
  309.         icont prog2 prog1.u
  310.  
  311. Ucode files also can be added to a program when it is linked by
  312. using the link declaration in an Icon source program as described
  313. in [2].
  314.  
  315.    The informative messages from the translator and linker can be
  316. suppressed by using the -s option.  Normally, both informative
  317. messages and error messages are sent to standard error output.
  318.  
  319.    A name other than the default one for the icode file produced
  320. by the Icon linker can be specified by using the -o option, fol-
  321. lowed by the desired name. For example,
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. IPD136                        - 5 -                 April 2, 1990
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.         icont prog.icn
  338.         ilink -o probe.icx prog.u1
  339.  
  340. produces the icode file named probe.icx rather than prog.icx.
  341.  
  342.    Icon source programs may be read from standard input.  The
  343. argument - signifies the use of standard input as a source file.
  344. In this case, the ucode files are named stdin.u1 and stdin.u2 and
  345. the icode file is named stdin.icx.
  346.  
  347.    Normally, &trace has an initial value of 0.  The -t option to
  348. icont causes &trace to have an initial value of -1 when the pro-
  349. gram is executed.
  350.  
  351.    The option -u to icont causes warning messages to be issued
  352. for undeclared identifiers in the program.  The warnings are
  353. issued during the linking phase.
  354.  
  355.    Icon has several tables related to the translation and linking
  356. of programs.  These tables are large enough for most programs,
  357. but translation or linking is terminated with an error message,
  358. indicating the offending table, if there is not enough room.  If
  359. this happens, larger table sizes can be specified by using the -S
  360. option. This option has the form -S[cfgilnrstCFL]n, where the
  361. letter following the S specifies the table and n is the number of
  362. storage units to allocate for the table.
  363.  
  364.      c  constant table          100
  365.      f  field table             100
  366.      g  global symbol table     200
  367.      i  identifier table        500
  368.      l  local symbol table      100
  369.      l  line number table      1000
  370.      r  record table            100
  371.      s  string space          20000
  372.      t  tree space            15000
  373.      C  code buffer           15000
  374.      F  file names               10
  375.      L  labels                  500
  376.  
  377.  
  378. The options must be specified both for icont and ilink and must
  379. have the same values for both.
  380.  
  381.    The units depend on the table involved, but the default values
  382. can be used as guides for appropriate settings of -S options
  383. without knowing the units.  For example,
  384.  
  385.         icont -Sc200 -Sg600 prog.icn
  386.  
  387. translates and links prog.icn with twice the constant table space
  388. and three times the global symbol table space that ordinarily
  389. would be provided.
  390.  
  391.  
  392.  
  393.  
  394. IPD136                        - 6 -                 April 2, 1990
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403. 6.3__Environment_Variables
  404.  
  405.    When an Icon program is executed, several environment vari-
  406. ables are examined to determine execution parameters.  The values
  407. assigned to these variables should be numbers.
  408.  
  409.    Environment variables are particularly useful in adjusting
  410. Icon's storage requirements. This may be necessary if your com-
  411. puter does not have enough memory to run programs that require an
  412. unusually large amount of data.  Particular care should be taken
  413. when changing default sizes: unreasonable values may cause Icon
  414. to malfunction.
  415.  
  416.    The following environment variables can be set to affect
  417. Icon's execution parameters. Their default values are listed in
  418. parentheses after the environment variable name:
  419.  
  420.         TRACE (undefined).  This variable initializes the value
  421.      of &trace.  If this variable has a value, it overrides the
  422.      translation-time -t option.
  423.  
  424.         NOERRBUF (undefined).  If this variable is set, &errout
  425.      is not buffered.
  426.  
  427.         STRSIZE (65000). This variable determines the size, in
  428.      bytes, of the region in which strings are stored.
  429.  
  430.         HEAPSIZE (65000).  This variable determines the size, in
  431.      bytes, of the region in which Icon allocates lists, tables,
  432.      and other objects.
  433.  
  434.         MSTKSIZE (10000). This variable determines the size, in
  435.      words, of the main interpreter stack.
  436.  
  437.         QLSIZE (5000). This variable determines the size, in
  438.      bytes, of the region used by the garbage collector for
  439.      pointers to strings.
  440. The maximum region size is 65000.  Specifying a larger size may
  441. cause program malfunction or unexpected results.
  442.  
  443.  
  444. 7.__Memory_Utilization
  445.  
  446.    Icon requires a significant amount of memory. It may not run
  447. or it may run slowly if enough memory is not available.
  448.  
  449.    The executor, iconx, reserves 200KB of RAM for its use. If
  450. that amount is not available, it aborts with a setblock failure.
  451. Note that using a RAM disk may be a problem in this regard.
  452.  
  453.    For some programs, it may be necessary to reduce the default
  454. region sizes.  For example, under ASH
  455.  
  456.  
  457.  
  458.  
  459.  
  460. IPD136                        - 7 -                 April 2, 1990
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.         set STRSIZE=40000
  470.  
  471. sets the size of the string region to 40KB.
  472.  
  473.  
  474. 8.__Features_of_Icon_for_the_Atari_ST_
  475.  
  476.    Icon for the Atari ST supports all the features of Version 8
  477. of Icon, with the following exceptions and additions:
  478.  
  479.      +  The -x option to icont for automatic execution is not
  480.         supported.
  481.  
  482.      +  Large-integer arithmetic is not supported.
  483.  
  484.      +  Pipes are not supported. A file cannot be opened with the
  485.         "p" option.
  486.  
  487.      +  There are two additional options for open: "t" and "u".
  488.         The "t" option, which is the default, indicates that the
  489.         file is to be translated into UNIX* format.  All
  490.         carriage-return/line-feed sequences are translated into
  491.         line-feed characters on both input and output.  The "u"
  492.         option indicates that the file is to be untranslated.
  493.         Examples are:
  494.  
  495.                 untranfile := open("test.fil","ru")
  496.                 tranfile := open("test.new","wt")
  497.  
  498.  
  499.      For files opened in the translate mode, the position pro-
  500.      duced by seek() may not reflect the actual byte position
  501.      because of the translation of carriage-return/line-feed
  502.      sequences to line-feed characters.
  503.  
  504.      +  The following Atari ST device names can be used as file
  505.         names:
  506.  
  507.                 console        CON
  508.                 printer        PRN
  509.                 auxiliary deviceAUX
  510.                 null           NUL
  511.  
  512.         For example,
  513.  
  514.                 prompt := open("CON","w")
  515.  
  516.         causes strings written to prompt to be displayed on the
  517.         console.  Use of a null file name means no file is
  518.         created.  These special names are associated with the
  519.         devices above even if device designations or filename
  520. __________________________
  521. *UNIX is a trademark of AT&T Bell Laboratories.
  522.  
  523.  
  524.  
  525.  
  526. IPD136                        - 8 -                 April 2, 1990
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.         extensions are added to them.  For example, A:CON.XXX
  536.         refers to the console and is not the name of a disk file.
  537.  
  538.  
  539. 9.__Bugs
  540.  
  541.    The known bugs in all implementations of Icon are listed in
  542. [2].
  543.  
  544.    There are two known bugs in Icon for the Atari ST:
  545.  
  546.      +  The -e on the command line to iconx to redirect error
  547.         output does not work properly.
  548.  
  549.      +  The system() function may not work properly.
  550.  
  551.  
  552. 10.__Reporting_Problems
  553.  
  554.    Problems with Icon should be noted on a trouble report form
  555. (included with the distribution) and sent to
  556.  
  557.         Icon Project
  558.         Department of Computer Science
  559.         Gould-Simpson Building
  560.         The University of Arizona
  561.         Tucson, AZ   85721
  562.         U.S.A.
  563.         (602) 621-4049
  564.         icon-project@cs.arizona.edu     (Internet)
  565.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  566.  
  567.  
  568.  
  569. 11.__Registering_Copies_of_Icon
  570.  
  571.    If you received your copy of Version 8 of Icon directly from
  572. the Icon Project, it has been registered in your name and you
  573. will receive the Icon Newsletter without charge. This Newsletter
  574. contains information about new implementations, updates, program-
  575. ming techniques, and information of general interest about Icon.
  576.  
  577.    If you received your copy of Version 8 of Icon from another
  578. source, please fill out the registration form that is included in
  579. the documents in the distribution) and send it to the Icon Pro-
  580. ject at the address listed above. This will entitle you to a free
  581. subscription to the Icon Newsletter and assure that you receive
  582. information about updates.
  583.  
  584. Acknowledgements
  585.  
  586.    The design and development of the Icon programming language
  587. was supported, in part, by the National Science Foundation.
  588.  
  589.  
  590.  
  591.  
  592. IPD136                        - 9 -                 April 2, 1990
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.    Many individuals contributed to the design and implementation
  602. of Icon. The principal ones are Cary Coutant, Dave Gudeman, Dave
  603. Hanson, Tim Korb, Bill Mitchell, Kelvin Nilsen, Janalee O'Bagy,
  604. Gregg Townsend, Ken Walker, and Steve Wampler.
  605.  
  606.    Owen Fonorow and Jerry Nowlin did the original implementation
  607. of Icon for the Atari ST.  Charles Richmond made significant con-
  608. tributions to subsequent versions.
  609.  
  610. References
  611.  
  612.  
  613. 1.   R. E. Griswold, An Overview of Version 8 of the Icon
  614.      Programming Language, The Univ. of Arizona Tech. Rep. 90-6,
  615.      1990.
  616.  
  617. 2.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  618.      Tech. Rep. 90-1, 1990.
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658. IPD136                       - 10 -                 April 2, 1990
  659.  
  660.  
  661.